Kebijakan izin

Kebijakan izin mengontrol apakah alat yang dijalankan server (kumpulan alat agen pra-bangun dan kumpulan alat MCP) berjalan secara otomatis atau menunggu persetujuan Anda. Alat khusus dijalankan oleh aplikasi Anda dan dikendalikan oleh Anda, jadi tidak diatur oleh kebijakan izin.

Semua permintaan Managed Agents API memerlukan header beta managed-agents-2026-04-01. SDK menetapkan header beta secara otomatis.

Jenis kebijakan izin

Kebijakan	Perilaku
`always_allow`	Alat dijalankan secara otomatis tanpa konfirmasi.
`always_ask`	Sesi mengeluarkan acara `session.status_idle` dan menunggu acara `user.tool_confirmation` sebelum dijalankan.

Tetapkan kebijakan untuk kumpulan alat

Izin kumpulan alat agen

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

default_config adalah pengaturan opsional. Jika Anda menghilangkannya, kumpulan alat agen akan diaktifkan dengan kebijakan izin default, always_allow.

Izin kumpulan alat MCP

Kumpulan alat MCP secara default menggunakan always_ask. Ini memastikan bahwa alat baru yang ditambahkan ke server MCP tidak dijalankan dalam aplikasi Anda tanpa persetujuan. Untuk menyetujui otomatis alat dari server MCP yang terpercaya, atur permission_policy pada entri mcp_toolset.

mcp_server_name harus cocok dengan name yang direferensikan dalam array mcp_servers.

Contoh ini menghubungkan server MCP GitHub dan memungkinkan alatnya berjalan tanpa konfirmasi:

Ganti kebijakan alat individual

Gunakan array configs untuk mengganti default untuk alat individual. Contoh ini memungkinkan kumpulan alat agen lengkap secara default tetapi memerlukan konfirmasi sebelum perintah bash apa pun dijalankan:

Merespons permintaan konfirmasi

Ketika agen memanggil alat dengan kebijakan always_ask:

Sesi mengeluarkan acara agent.tool_use atau agent.mcp_tool_use.
Sesi dijeda dengan acara session.status_idle yang berisi stop_reason: requires_action. ID acara pemblokiran ada dalam array stop_reason.requires_action.event_ids.
Kirim acara user.tool_confirmation untuk masing-masing, meneruskan ID acara dalam parameter tool_use_id. Atur result ke "allow" atau "deny". Gunakan deny_message untuk menjelaskan penolakan.
Setelah semua acara pemblokiran diselesaikan, sesi beralih kembali ke running.

Pelajari lebih lanjut tentang penanganan acara dalam panduan aliran acara sesi.

Alat khusus

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

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

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

tools = [
    {
        "type": "agent_toolset_20260401",
        "default_config": {
            "permission_policy": {"type": "always_allow"},
        },
        "configs": [
            {
                "name": "bash",
                "permission_policy": {"type": "always_ask"},
            },
        ],
    },
]

# Izinkan alat untuk dijalankan
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.",
        },
    ],
)