Amankan deployment Managed Agents Anda

Panduan ini mencantumkan pengaturan yang membatasi apa yang dapat dijangkau dan dilakukan oleh agen di Claude Managed Agents, diurutkan dari yang paling penting. Setiap bagian menautkan ke halaman yang membahas pengaturan tersebut secara lengkap.

Risiko keamanan dan batasan sandbox menjelaskan mengapa pengaturan ini penting dan apa yang tidak dilindunginya. Untuk meninjau dan memantau sesi, lihat Tinjau dan pantau sesi agen.

Pilih tempat agen berjalan

Tempat alat agen berjalan menentukan siapa yang mengamankan sandbox: Anthropic, dengan environment cloud, atau Anda, dengan sandbox self-hosted. Untuk memilih di antara keduanya dan mempelajari apa yang sampai ke Anthropic pada masing-masing opsi, lihat Memilih lingkungan agen.

Jika Anda menggunakan sandbox self-hosted, perhatikan empat poin berikut:

• Jaringan: Batasi jaringan berlaku untuk environment cloud. Untuk sandbox self-hosted, tetapkan batas yang setara pada lalu lintasnya di firewall Anda sendiri. Firewall Anda tidak membatasi server MCP yang dideklarasikan agen, jadi tinjau server tersebut, serta server apa pun yang ditetapkan aplikasi Anda untuk sebuah sesi.
• Alat web: Alat web berjalan di server Anthropic, sehingga firewall Anda tidak membatasinya. Batasi alat tersebut dengan daftar domainnya. Lihat Batasi web search dan web fetch.
• Kredensial: Kredensial variabel lingkungan belum didukung pada sandbox self-hosted.
• Isolasi dan hardening: Anda bertanggung jawab atas keduanya. Lihat Model keamanan.

Tidak ada opsi yang mengubah cakupan kepatuhan Managed Agents atau berapa lama riwayat sesi disimpan. Lihat Pantau sesi dan tinjau retensi.

Batasi jaringan

Tetapkan networking.type ke limited dan cantumkan hanya host yang dibutuhkan agen di allowed_hosts. Permintaan pembuatan environment yang tidak menyertakan networking mungkin mendapatkan unrestricted, jadi tetapkan networking di setiap permintaan pembuatan. Lihat Risiko jaringan tanpa batasan.

File, memory store, dan repositori GitHub yang Anda lampirkan tetap tersedia bagi agen terlepas dari allowed_hosts.

Contoh di halaman ini menggunakan agen dukungan. Agen ini membaca tiket pelanggan, mencari pesanan, membaca pusat bantuan Anda, dan menyusun draf balasan. Aplikasi Anda menjalankan pencarian pesanan, yang tidak memerlukan host, sehingga environment ini mengizinkan satu host, yaitu pusat bantuan, untuk web_fetch:

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: support-agent
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - help.example.com

Environment limited memiliki tiga pengaturan jaringan:

Pengaturan allow_package_managers dan allow_mcp_servers tidak menambahkan host untuk web search dan web fetch.

Biarkan allow_mcp_servers nonaktif, yang merupakan default, dan cantumkan host setiap server MCP yang Anda operasikan atau percayai di allowed_hosts. Setiap host yang Anda cantumkan juga terbuka bagi kode di sandbox. Dengan allow_mcp_servers nonaktif, pemeriksaan saat pembuatan sesi menolak permintaan jika host server MCP tidak tercantum. Lihat Menyediakan autentikasi saat pembuatan sesi. Pemeriksaan yang sama dijalankan saat pembaruan sesi mengubah mcp_servers.

Saat Anda memilih host untuk allowed_hosts, ikuti dua aturan berikut:

• Cantumkan hanya host yang Anda operasikan atau percayai.
• Hindari wildcard *. dan domain shared-hosting tempat siapa pun dapat memublikasikan konten.

Jika agen tetap memiliki bash, tetapkan kebijakan izin alat bash seperti yang dijelaskan di Setujui tindakan berisiko.

Lihat Penyiapan environment cloud untuk setiap pengaturan jaringan.

Simpan kredensial di vault

Simpan setiap rahasia di vault. Untuk setiap kredensial variabel lingkungan, tetapkan lokasi injeksi hanya ke header permintaan dan cantumkan hanya host yang menjadi tujuan rahasia tersebut. Kode di sandbox melihat placeholder alih-alih rahasia. Managed Agents menukar placeholder dengan rahasia asli hanya dalam permintaan HTTPS keluar ke host yang diizinkan kredensial. Dengan demikian, rahasia tetap berada di luar jangkauan langsung model, kecuali jika suatu layanan mengirimkannya kembali, seperti endpoint yang menggemakan header permintaan. Jika networking kredensial adalah unrestricted, Managed Agents memasukkan rahasia asli ke dalam permintaan ke host mana pun yang dapat dijangkau sandbox menurut environment. Untuk menggunakan vault, teruskan ID-nya di vault_ids saat Anda membuat sesi atau deployment.

Agen dukungan tidak memerlukan kredensial vault, karena aplikasi Anda memegang kunci API untuk API pesanan Anda. Jika agen Anda memegang kredensial vault, lihat Menambahkan kredensial untuk permintaan dalam setiap bahasa.

Jauhkan kunci dari prompt sistem, definisi agen, dan pesan. Jangan berikan kunci API Claude kepada agen. Bahkan ketika kunci API Claude berada di vault, kode di sandbox dapat menggunakannya untuk memanggil Claude API secara langsung. Kode tersebut dapat melakukan apa pun yang diizinkan kunci itu, seperti memulai atau menghapus sesi, atau menggunakan web search dan web fetch. Pengaturan alat, persetujuan, dan anggaran agen tidak berlaku untuk panggilan tersebut. Dalam environment limited, kode dapat melakukan panggilan ini hanya jika allowed_hosts memungkinkan sandbox menjangkau api.anthropic.com.

Ambil token sendiri dan simpan di vault, karena token yang diambil oleh kode di sandbox dengan rahasia yang tersimpan akan kembali tanpa disensor.

Simpan vault untuk beban kerja dengan tingkat kepercayaan berbeda di workspace terpisah, karena kunci API apa pun yang memiliki akses ke suatu workspace dapat mereferensikan vault-nya. Gunakan kunci API yang cakupannya terbatas pada satu workspace.

Lihat Autentikasi dengan vault untuk kredensial MCP dan rotasi.

Batasi web search dan web fetch

Tetapkan allowed_domains pada web_fetch ke situs yang dibutuhkan agen. URL apa pun yang diambil agen dapat membawa data ke situs yang ditujunya, sehingga daftar ini merupakan kontrol keamanan. Pada web_search, tetapkan allowed_domains ke situs yang hasilnya Anda inginkan, sehingga hasil hanya berasal dari situs yang Anda percayai keakuratannya. Daftar ini tidak mencegah kueri pencarian sampai ke penyedia pencarian. Hasil pencarian menyertakan teks dari halaman, sehingga daftar ini juga membatasi teks dari situs mana yang sampai ke agen. Tetapkan allowed_domains pada kedua alat untuk setiap jenis environment.

Daftar blocked_domains memblokir host yang Anda cantumkan beserta subdomainnya, dan tidak ada host lain. Konten yang sama masih dapat sampai ke agen dari arsip web, cache, mirror, atau domain terkait yang tidak Anda cantumkan. Jangan mengandalkan blocked_domains untuk keamanan. Gunakan allowed_domains dan sebutkan host yang Anda percayai.

Dalam environment limited, daftar allowed_hosts dari Batasi jaringan juga membatasi alat web. Environment unrestricted atau sandbox self-hosted tidak membatasi alat web.

Kedua daftar mencocokkan host secara berbeda:

Jika agen membutuhkan sebuah situs beserta semua subdomainnya, cantumkan example.com dan *.example.com di allowed_hosts, dan jika tidak, cantumkan host yang persis. Jika sebuah alat mencantumkan example.com dan allowed_hosts hanya mencantumkan *.example.com, sesi tetap dibuat. Pemeriksaan saat pembuatan sesi menganggap example.com berada dalam *.example.com, tetapi alat tidak mengembalikan apa pun dari example.com itu sendiri. Lihat Menetapkan daftar domain pada agen untuk cara kedua daftar melakukan pencocokan.

Alat web_fetch juga hanya membuka URL yang sudah muncul dalam sesi:

Dalam sesi multiagen, web_fetch membuka URL dari agen lain hanya jika URL tersebut sampai ke agen itu melalui sumber yang ditandai Ya. Hasil alat kustom dari panggilan langsung dihitung sebagai sumber yang ditandai Ya. Ini berlaku bahkan jika Claude yang menulis teksnya, misalnya ketika alat mengulang inputnya. URL dapat dihitung bahkan ketika ditulis tanpa https://, seperti example.com/docs. Alat web_fetch tidak selalu dapat membuka tautan yang menampilkan kata-kata alih-alih URL-nya, seperti "Hubungi dukungan." Jika agen harus mengambil URL yang belum muncul dalam sesi, kirimkan URL tersebut dalam pesan pengguna.

Aturan ini mengurangi kemungkinan teks yang diinjeksi membangun URL yang membawa data pribadi. Teks pengguna akhir, hasil pencarian, halaman yang diambil, dan hasil alat kustom masih dapat menambahkan URL, jadi tetap tetapkan allowed_domains. Messages API menerapkan aturan serupa dengan daftar sumber yang berbeda. Lihat Validasi URL.

Daftar domain pada web_fetch tidak membatasi alat bash. Batasi jaringan juga. Lihat Aturan daftar domain.

Setujui tindakan berisiko

Tetapkan auto pada bash, write, edit, dan web_fetch, serta pada alat MCP yang hanya membaca data. Gunakan always_ask sebagai gantinya pada alat jika Anda tidak dapat membatalkan perubahannya di luar sandbox. Gunakan juga pada alat yang tidak boleh berjalan hanya karena teks pengguna akhir yang Anda teruskan memintanya. Kebijakan izin menentukan apakah panggilan alat berjalan, menunggu persetujuan Anda, atau dievaluasi oleh server.

Toolset di Berikan agen set alat terkecil menerapkan kebijakan ini.

Kebijakan auto memungkinkan server menjalankan panggilan, menolaknya, atau menjeda untuk persetujuan. Seseorang tidak dapat menyetujui setiap panggilan dalam eksekusi yang panjang, sehingga server memeriksa setiap panggilan sebagai gantinya. Pasangkan auto dengan jaringan terbatas, kunci dengan izin sempit, anggaran, dan peringatan pada sesi idle. auto bukan titik pemeriksaan manusia, jadi jika seseorang harus meninjau panggilan suatu alat sebelum berjalan, konfigurasikan always_ask pada alat tersebut.

auto memperlakukan teks dalam event user.message dan deskripsi dalam event user.define_outcome sebagai instruksi Anda, termasuk teks pengguna akhir yang Anda teruskan.

Sesi yang dijeda menunggu tanpa batas waktu, sehingga sesi tanpa pengawasan memerlukan klien yang menjawab panggilan yang dijeda atau menginterupsi sesi.

Tinjau setiap panggilan yang dijeda sebelum Anda mengizinkannya. Klien yang mengizinkan setiap panggilan tanpa menunjukkannya kepada seseorang sama dengan always_allow. Lihat Merespons permintaan konfirmasi dan Melihat bagaimana setiap panggilan dievaluasi.

Berikan agen set alat terkecil

Tetapkan default_config.enabled ke false dan aktifkan hanya alat yang dibutuhkan agen. Toolset agen mengaktifkan kedelapan alat bawaan secara default.

Agen dukungan membutuhkan tiga alat bawaan: read dan write untuk drafnya, dan web_fetch untuk pusat bantuan. Agen ini mencari pesanan melalui alat kustom, lookup_order, yang dijalankan aplikasi Anda. Aplikasi Anda memegang kunci API untuk API pesanan Anda, sehingga agen tidak memerlukan bash maupun kredensial.

Contoh berikut membatasi web_fetch ke help.example.com dengan allowed_domains. Contoh ini menetapkan auto pada write dan web_fetch, seperti yang direkomendasikan di Setujui tindakan berisiko. Jika tiket pelanggan mendorong agen menggunakan alat ini, agen hanya dapat mengubah file di sandbox atau membuka halaman pusat bantuan. Itulah sebabnya kedua alat tidak memerlukan always_ask. Contoh ini juga menetapkan always_ask di default_config, sehingga alat yang Anda aktifkan kemudian tanpa kebijakannya sendiri menggunakan always_ask:

ant apply agent.md

---
name: Support Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: false
      permission_policy:
        type: always_ask
    configs:
      - name: read
        enabled: true
        permission_policy:
          type: always_allow
      - name: write
        enabled: true
        permission_policy:
          type: auto
      - name: web_fetch
        enabled: true
        allowed_domains: [help.example.com]
        permission_policy:
          type: auto
  - type: custom
    name: lookup_order
    description: Look up one order by its ID. Returns the status, the items, and the delivery date.
    input_schema:
      type: object
      properties:
        order_id:
          type: string
          description: The order ID from the ticket
      required:
        - order_id
---

Pembaruan agen menggantikan seluruh array tools, jadi kirimkan setiap entri yang ingin Anda pertahankan.

Pembaruan agen hanya menjangkau sesi baru, jadi periksa juga deployment, agen yang mencantumkan agen ini, dan sesi yang sudah ada:

• Deployment menyematkan versi agen, jadi arahkan setiap deployment ke versi yang baru.
• Agen yang mencantumkan agen ini di subagents.predefined_agents atau workflows.predefined_agents mempertahankan versi yang disematkannya, jadi perbarui agen tersebut juga.
• Untuk memperketat sesi yang sudah ada, perbarui alat sesi tersebut. Sesi harus dalam status idle, dan pembaruan menggantikan seluruh array tools. Dalam sesi multiagen, daftar allowed_domains dan blocked_domains baru pada alat web agen yang dijalankan sesi juga berlaku untuk setiap agen lainnya. Daftar tersebut berlaku mulai giliran berikutnya dari setiap agen. Alat yang diaktifkan dan kebijakan izin agen-agen tersebut tidak berubah. Untuk mengubahnya, perbarui setiap agen, lalu mulai sesi baru.

Batasi juga server MCP dan alat kustom sesuai kebutuhan agen:

• Server MCP: Toolset MCP mengaktifkan setiap alat yang diekspos server secara default. Tetapkan default_config.enabled ke false dan aktifkan alat yang disebutkan namanya, sehingga alat yang ditambahkan server kemudian tetap nonaktif. Hapus server yang tidak digunakan agen. Lihat Konektor MCP.
• Alat kustom: Aplikasi Anda yang menjalankannya, dan kebijakan izin tidak berlaku. Validasi input setiap panggilan di aplikasi Anda dan batasi apa yang dapat disentuh alat tersebut.

Jauhkan input tidak tepercaya dari alat yang kuat

Periksa alat dan kredensial mana yang dimiliki agen setiap kali agen membaca input tidak tepercaya, yaitu teks yang dapat ditulis oleh seseorang di luar tim Anda. Bagian ini menggunakan dua istilah:

• Input tidak tepercaya: Halaman web, hasil pencarian, tiket dukungan, email, file repositori, unggahan, hasil server MCP, dan pesan pengguna akhir yang Anda teruskan.
• Alat yang kuat: bash, write, edit, web_fetch, web_search, alat MCP dan alat kustom yang menulis atau mengirim data, serta alat apa pun yang menggunakan kredensial.

Teks dalam input tidak tepercaya dapat memerintahkan agen untuk menggunakan alat kuat yang dimilikinya. Agen dukungan membaca tiket, sehingga agen ini menjangkau API pesanan Anda hanya melalui alat kustom lookup_order. Aplikasi Anda memeriksa bahwa pesanan tersebut milik pengirim tiket.

Dalam environment cloud, membaca file dengan read juga dapat memuat file CLAUDE.md dan AGENTS.md sebagai instruksi. File tersebut dimuat dari direktori file dan direktori induknya, hingga direktori kerja sandbox. File yang direferensikannya dengan @ dan sebuah path, seperti @docs/setup.md, juga dimuat, hingga kedalaman lima referensi. Referensi dapat menunjuk ke mana saja di sandbox, misalnya @/etc/hosts. Tidak ada pengaturan yang menonaktifkan ini selain menonaktifkan read, jadi perlakukan repositori, paket, atau arsip yang dapat ditulis oleh seseorang di luar tim Anda sebagai input tidak tepercaya.

Ketika agen harus membaca input tidak tepercaya sekaligus bertindak, panduan ini merekomendasikan salah satu dari tiga desain:

• Pisahkan membaca dari bertindak. Dalam satu sesi multiagen, agen utama memberikan tugas kepada fetcher, yang membaca web, dan writer, yang mengubah file atau catatan.
• Berikan agen satu alat kustom yang sempit. Aplikasi Anda menjalankan alat tersebut, memeriksa inputnya, dan memegang kredensial. Agen dukungan menggunakan desain ini, bukan pemisahan. Lihat Menjawab panggilan alat yang menjeda sesi.
• Libatkan seseorang dalam prosesnya. Gunakan always_ask pada alat yang kuat sehingga seseorang menyetujui setiap panggilan.

Pemisahan menggunakan tiga agen:

Hasil fetcher dibangun dari halaman tidak tepercaya, dan agen utama dapat meneruskan teksnya ke writer. Pertahankan auto atau always_ask pada alat writer. Fetcher masih dapat mengirim sebagian dari apa yang dibacanya ke situs dalam daftar web_fetch-nya, dan ke penyedia pencarian dalam kuerinya.

Agen dalam satu sesi multiagen berbagi sandbox, file-nya, dan kredensial vault, sehingga pemisahan ini hanya memisahkan alat dan percakapan mereka. Untuk pemisahan yang lebih kuat, gunakan dua sesi dengan environment dan vault terpisah. Minta aplikasi Anda hanya meneruskan field tetap, seperti ID pesanan, di antara kedua sesi.

Tetapkan batas dan cara untuk menghentikan

Tetapkan anggaran saat Anda membuat setiap sesi, dan tentukan sebelumnya bagaimana Anda menghentikan agen.

Untuk menghentikan agen yang sedang berjalan, ikuti langkah-langkah berikut:

1. Kirim user.interrupt saja.
2. Untuk agen terjadwal, jeda juga deployment agar tidak ada eksekusi terjadwal baru yang dimulai. Untuk mengakhiri jadwal secara permanen, arsipkan deployment.
3. Jika sebuah kunci mungkin terekspos, rotasikan kunci tersebut di layanan yang menerbitkannya.
4. Jika agen memiliki eksekusi workflow yang terbuka, kirim juga user.message yang memintanya menghentikan eksekusi tersebut, karena interupsi tidak mengakhiri eksekusi. Lihat Menginterupsi sesi dengan eksekusi yang terbuka untuk panggilan alat yang perlu dibatalkan terlebih dahulu.
5. Tunggu hingga sesi menjadi idle. Sesi yang sedang berjalan tidak dapat diarsipkan atau dihapus.
6. Arsipkan sesi untuk menyimpan riwayatnya. Hapus sesi saat Anda tidak lagi memerlukan riwayatnya.

Interupsi tidak membatalkan apa yang sudah dilakukan atau dikirim agen. Mengarsipkan agen tidak menghentikan sesinya yang sedang berjalan.

max_list_cost.amount pada anggaran adalah bilangan bulat dalam sen AS yang ditulis sebagai string, sehingga "125" berarti $1,25. Lihat Menetapkan anggaran saat pembuatan sesi.

Anda tidak dapat menambahkan anggaran ke sesi yang dibuat tanpa anggaran. Untuk mengubah atau menghapus batas, lihat Melanjutkan sesi yang mencapai anggarannya. Setelah Anda menghapus batas sesi, Anda tidak dapat menetapkan batas baru.

Anggaran membatasi pengeluaran, tetapi tidak membatasi apa yang dilakukan agen sebelum mencapai batas. Untuk memisahkan beban kerja dengan tingkat kepercayaan berbeda, gunakan workspace terpisah. Berikan setiap beban kerja kunci API yang cakupannya terbatas pada satu workspace, karena kunci yang dapat menjangkau beberapa workspace dapat bertindak di workspace mana pun di antaranya.

Lihat Anggaran sesi, Operasi sesi, dan Deployment terjadwal.

Langkah selanjutnya