Kebijakan izin

Kebijakan izin mengontrol apakah alat yang dieksekusi oleh server (toolset agen bawaan dan toolset MCP) berjalan secara otomatis atau menunggu persetujuan Anda. Alat kustom dieksekusi oleh aplikasi Anda dan dikendalikan oleh Anda, sehingga 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 dieksekusi secara otomatis tanpa konfirmasi.
`always_ask`	Sesi memancarkan event `session.status_idle` dan menunggu event `user.tool_confirmation` sebelum dieksekusi.

Tetapkan kebijakan untuk toolset

Izin toolset 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, toolset agen akan 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 di aplikasi Anda tanpa persetujuan. Untuk menyetujui alat secara otomatis dari server MCP yang tepercaya, tetapkan 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 mengizinkan alatnya berjalan tanpa konfirmasi:

Timpa kebijakan alat individual

Gunakan array configs untuk menimpa default untuk alat individual. Contoh ini mengizinkan seluruh toolset agen secara default tetapi memerlukan konfirmasi sebelum perintah bash apa pun dijalankan:

Merespons permintaan konfirmasi

Ketika agen memanggil alat dengan kebijakan always_ask:

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

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

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.

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }')

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Dev Assistant",
    "model": "claude-sonnet-4-6",
    "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"}
        }
      }
    ]
  }')

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

# Izinkan alat untuk dieksekusi
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$AGENT_TOOL_USE_EVENT_ID'",
        "result": "allow"
      }
    ]
  }'

# Atau tolak dengan penjelasan
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "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."
      }
    ]
  }'