Kebijakan izin

Kebijakan izin mengontrol apakah alat yang dieksekusi server (toolset agen bawaan dan toolset MCP) berjalan secara otomatis atau menunggu persetujuan Anda. Alat kustom dieksekusi oleh aplikasi Anda dan dikontrol oleh Anda, sehingga tidak diatur oleh kebijakan izin.



Jenis kebijakan izin

Setiap jenis toolset memiliki default-nya sendiri: toolset agen secara default menggunakan always_allow, dan toolset MCP secara default menggunakan 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 beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
YAML

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



Izin toolset MCP

Toolset MCP secara default menggunakan always_ask. Ini memastikan bahwa alat baru yang ditambahkan ke server MCP tidak dieksekusi dalam 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 alatnya berjalan tanpa konfirmasi:

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-8
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
YAML



Mengganti kebijakan alat individual

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

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
YAML

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



Merespons permintaan konfirmasi

Ketika agen memanggil alat dengan kebijakan always_ask:

1. Sesi mengeluarkan 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 ada 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. Tetapkan 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 akan dieksekusi. Alat yang ditolak tidak berjalan, dan agen menerima hasil alat yang menyatakan bahwa panggilan ditolak, termasuk deny_message 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
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# Atau tolak dengan penjelasan
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{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