Kebijakan izin

"Permission policies" (kebijakan izin) mengontrol apakah alat yang dieksekusi server, yaitu "toolset" (kumpulan alat) agen bawaan dan toolset MCP, berjalan secara otomatis, menunggu persetujuan Anda, atau setiap panggilannya dievaluasi oleh server. "Custom tools" (alat kustom) dieksekusi dan dikendalikan oleh aplikasi Anda sendiri, sehingga tidak diatur oleh kebijakan izin.

Jenis kebijakan izin

Setiap jenis toolset memiliki default-nya sendiri: toolset agen default-nya always_allow, dan toolset MCP default-nya always_ask.

Kebijakan izin mengontrol kapan alat yang diaktifkan berjalan. Untuk menghapus alat dari agen sepenuhnya, nonaktifkan alat tersebut. Lihat Menonaktifkan alat tertentu.

Menetapkan kebijakan untuk toolset

Anda menetapkan kebijakan izin dalam konfigurasi tools agen saat Anda membuat agen, dan Anda dapat mengubahnya nanti dengan memperbarui agen. Sesi yang sedang berjalan mempertahankan konfigurasi toolset yang digunakan saat sesi tersebut dibuat. Pembaruan berlaku untuk sesi yang dibuat setelahnya.

Izin toolset agen

Saat membuat agen, Anda dapat menerapkan kebijakan ke setiap alat dalam agent_toolset_20260401 menggunakan default_config.permission_policy:

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
---

default_config bersifat opsional. Jika Anda menghilangkannya, toolset agen diaktifkan dengan kebijakan izin default, always_allow.

Izin toolset MCP

Toolset MCP default-nya always_ask. Ini memastikan bahwa alat baru yang ditambahkan ke server MCP tidak dieksekusi di aplikasi Anda tanpa persetujuan. Untuk menyetujui secara otomatis alat dari server MCP tepercaya, tetapkan default_config.permission_policy pada entri mcp_toolset.

mcp_server_name harus cocok dengan name dari server dalam array mcp_servers.

Contoh ini menghubungkan server MCP GitHub dan mengizinkan alat-alatnya berjalan tanpa konfirmasi:

ant apply agent.md

---
name: Dev Assistant
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: always_allow
---

Mengganti kebijakan alat individual

Gunakan array configs untuk mengganti default untuk alat individual. Nilai name untuk toolset agen tercantum di Alat yang tersedia. Contoh ini mengizinkan seluruh toolset agen secara default tetapi memerlukan konfirmasi sebelum perintah bash apa pun dijalankan:

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
---

Teruskan konfigurasi tools ini dalam permintaan pembuatan agen (tab CLI menampilkan perintah lengkapnya). Toolset MCP mendukung penggantian per alat yang sama, dengan name diatur ke nama alat yang dilaporkan oleh server MCP. Lihat Mengonfigurasi alat MCP mana yang tersedia.

Biarkan server mengevaluasi setiap panggilan dengan auto

Dengan kebijakan izin auto, server mengevaluasi setiap panggilan sebelum dijalankan. Karena evaluasi mempertimbangkan alat, input panggilan, dan konten sesi hingga titik tersebut, server dapat memperlakukan dua panggilan ke alat yang sama secara berbeda. Setiap panggilan memiliki salah satu dari tiga hasil:

• Panggilan dijalankan. Ketika server menentukan bahwa panggilan tersebut aman, alat dijalankan seperti di bawah always_allow.
• Panggilan ditolak. Ketika server mengevaluasi panggilan sebagai berisiko tinggi, alat tidak dijalankan. Agen menerima hasil alat berupa error dengan konten Permission to use {tool_name} has been denied. dan is_error: true. Sesi tetap berjalan, dan klien Anda tidak dapat membatalkan penolakan tersebut.
• Panggilan dijeda untuk meminta persetujuan Anda. Ketika server tidak mencapai keputusan, sesi dijeda seperti di bawah always_ask. Lihat Menanggapi permintaan konfirmasi.

Untuk mengaktifkan auto, atur permission_policy ke {"type": "auto"}. Pengaturan ini ditempatkan di dua tempat yang sama seperti kebijakan lainnya: default_config milik toolset untuk seluruh toolset, atau entri configs untuk satu alat. Toolset agen dan toolset MCP sama-sama menerimanya. Tidak ada toolset yang menggunakan auto secara default.

Contoh berikut menetapkan auto sebagai default untuk toolset agen dan untuk toolset MCP github, serta menimpa bash menjadi always_ask:

ant apply agent.md

---
name: Ops Agent
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: auto
    configs:
      - name: bash
        permission_policy:
          type: always_ask
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: auto
---

Apa yang Anda kirim dalam event user.message dihitung sebagai niat Anda, dan hal itu dapat membuat server mengizinkan panggilan yang sebaliknya akan ditolak. Server tidak membaca niat dari hasil alat, halaman web yang diambil, respons server MCP, atau pesan antar thread sesi. Server menilai konten tersebut tetapi tidak menerima instruksi darinya. Server mengevaluasi beberapa panggilan sebagai berisiko tinggi terlepas dari siapa yang memintanya. Jika Anda meneruskan input pengguna akhir yang tidak tepercaya dalam event user.message, server juga membaca input tersebut sebagai niat Anda, dan input itu dapat membuat suatu panggilan diizinkan. Konfigurasikan always_ask pada alat yang tidak akan Anda biarkan dijalankan oleh pengguna akhir tersebut tanpa peninjauan.

Melihat bagaimana setiap panggilan dievaluasi

Di bawah kebijakan izin apa pun, setiap event agent.tool_use dan agent.mcp_tool_use membawa evaluated_permission, yaitu hasil pemeriksaan izin panggilan tersebut: "allow", "ask", atau "deny". Sebagian besar event juga membawa objek evaluation yang type-nya menyebutkan kebijakan yang menghasilkan hasil tersebut. Di bawah auto, objek tersebut juga mencatat keputusan server, ditambah reason_code ketika hasilnya adalah ask atau deny.

Misalnya, ketika bash berada di bawah auto dan server mengevaluasi suatu panggilan sebagai berisiko tinggi, panggilan yang ditolak muncul di aliran event sebagai berikut:

{
  "type": "agent.tool_use",
  "id": "sevt_01pqr...",
  "name": "bash",
  "input": {
    "command": "rm -rf /workspace/reports"
  },
  "evaluated_permission": "deny",
  "evaluation": {
    "type": "auto",
    "evaluated_permission": {
      "type": "deny",
      "reason_code": "high_risk"
    }
  },
  "processed_at": "2026-03-25T14:05:12Z"
}

Objek evaluation mengambil salah satu bentuk dalam tabel berikut.

Ketika evaluation.type adalah "auto", evaluated_permission.type yang bersarang di dalamnya mengulang evaluated_permission tingkat atas milik event, sehingga Anda dapat membaca hasilnya dari salah satu field tersebut. reason_code adalah nilai yang dapat digunakan klien Anda untuk percabangan logika dan disimpan dalam catatan audit, bukan teks untuk ditampilkan kepada pengguna akhir.

evaluation tidak ada dalam dua kasus. Ketika agen menyebutkan alat yang tidak diaktifkan dalam sesi, server menolak panggilan tanpa mengevaluasi kebijakan: event membawa evaluated_permission: "deny" dan tanpa evaluation. Event yang dicatat sebelum evaluation diperkenalkan juga tidak menyertakannya: baca event tersebut sebagai always_allow ketika evaluated_permission adalah "allow" dan sebagai always_ask ketika nilainya "ask".

Tulis klien Anda agar dapat menoleransi evaluation.type atau reason_code yang tidak dikenalinya. Event agent.custom_tool_use tidak membawa kedua field tersebut, karena kebijakan izin tidak mengatur alat kustom.

Merespons permintaan konfirmasi

Panggilan alat dievaluasi menjadi ask di bawah kebijakan always_ask, atau di bawah auto ketika server tidak mencapai keputusan. Ketika hal itu terjadi:

1. Sesi memancarkan event agent.tool_use atau agent.mcp_tool_use.
2. Sesi dijeda dengan event session.status_idle yang stop_reason.type-nya adalah requires_action. ID event yang memblokir terdapat dalam array stop_reason.event_ids. Sesi menunggu respons tanpa batas waktu.
3. Kirim event user.tool_confirmation untuk setiap event yang memblokir, dengan meneruskan ID event dalam parameter tool_use_id. Atur result ke "allow" atau "deny". Gunakan deny_message untuk menjelaskan penolakan. Anda dapat mengirim beberapa konfirmasi dalam satu permintaan events.
4. Setelah semua event yang memblokir diselesaikan, sesi bertransisi kembali ke running. Alat yang diizinkan dieksekusi. Alat yang ditolak tidak berjalan, dan agen menerima hasil alat yang menyatakan bahwa panggilan ditolak, termasuk deny_message Anda.

Jika Anda mengirim user.tool_confirmation untuk event yang evaluated_permission-nya bukan ask, API menolaknya dengan error 400. Hal ini termasuk panggilan yang ditolak server di bawah auto: klien Anda tidak dapat membatalkannya.

Untuk menjawab secara interaktif, gunakan ant beta:sessions connect, yang menampilkan panggilan yang sedang menunggu dan mengirim event ini ketika Anda mengizinkan atau menolaknya. Lihat Menghubungkan ke sesi Managed Agents dari terminal Anda.

Dalam contoh berikut, ID event tool-use berasal dari array stop_reason.event_ids pada event session.status_idle. Pelajari lebih lanjut tentang menerima event dalam panduan Aliran event sesi, atau berlangganan webhook untuk mendapatkan notifikasi ketika sesi dijeda untuk menunggu input.

# Izinkan alat untuk dieksekusi
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# Atau tolak dengan penjelasan
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": mcp_tool_use_event.id,
            "result": "deny",
            "deny_message": "Don't create issues in the production project. Use the staging project.",
        },
    ],
)

Alat kustom

Kebijakan izin tidak berlaku untuk alat kustom. Ketika agen memanggil alat kustom, aplikasi Anda menerima event agent.custom_tool_use dan bertanggung jawab untuk memutuskan apakah akan mengeksekusinya sebelum mengirim kembali user.custom_tool_result. Lihat Aliran event sesi untuk alur lengkapnya.

Langkah selanjutnya