Politiche di autorizzazione

Le politiche di autorizzazione controllano se gli strumenti eseguiti dal server (il set di strumenti dell'agente precostruito e il set di strumenti MCP) vengono eseguiti automaticamente o in attesa della tua approvazione. Gli strumenti personalizzati vengono eseguiti dalla tua applicazione e controllati da te, quindi non sono governati dalle politiche di autorizzazione.

Tutte le richieste all'API Managed Agents richiedono l'intestazione beta managed-agents-2026-04-01. L'SDK imposta automaticamente l'intestazione beta.

Tipi di politiche di autorizzazione

Politica	Comportamento
`always_allow`	Lo strumento viene eseguito automaticamente senza conferma.
`always_ask`	La sessione emette un evento `session.status_idle` e attende un evento `user.tool_confirmation` prima di eseguire.

Impostare una politica per un set di strumenti

Autorizzazioni del set di strumenti dell'agente

Quando crei un agente, puoi facoltativamente applicare una politica a ogni strumento in agent_toolset_20260401 utilizzando default_config.permission_policy:

default_config è un'impostazione facoltativa. Se la ometti, il set di strumenti dell'agente verrà abilitato con la politica di autorizzazione predefinita, always_allow.

Autorizzazioni del set di strumenti MCP

I set di strumenti MCP predefiniti sono always_ask. Questo garantisce che i nuovi strumenti aggiunti a un server MCP non vengano eseguiti nella tua applicazione senza approvazione. Per approvare automaticamente gli strumenti da un server MCP affidabile, imposta permission_policy sulla voce mcp_toolset.

Il mcp_server_name deve corrispondere al name referenziato nell'array mcp_servers.

Questo esempio connette un server GitHub MCP e consente ai suoi strumenti di eseguirsi senza conferma:

Sovrascrivere la politica di uno strumento individuale

Utilizza l'array configs per sovrascrivere il valore predefinito per i singoli strumenti. Questo esempio consente il set di strumenti dell'agente completo per impostazione predefinita ma richiede conferma prima di eseguire qualsiasi comando bash:

Rispondere alle richieste di conferma

Quando l'agente richiama uno strumento con una politica always_ask:

La sessione emette un evento agent.tool_use o agent.mcp_tool_use.
La sessione si mette in pausa con un evento session.status_idle contenente stop_reason: requires_action. Gli ID degli eventi di blocco si trovano nell'array stop_reason.requires_action.event_ids.
Invia un evento user.tool_confirmation per ciascuno, passando l'ID dell'evento nel parametro tool_use_id. Imposta result su "allow" o "deny". Utilizza deny_message per spiegare un rifiuto.
Una volta risolti tutti gli eventi di blocco, la sessione torna a running.

Scopri di più sulla gestione degli eventi nella guida session event stream.

Strumenti personalizzati

Le politiche di autorizzazione non si applicano agli strumenti personalizzati. Quando l'agente richiama uno strumento personalizzato, la tua applicazione riceve un evento agent.custom_tool_use ed è responsabile di decidere se eseguirlo prima di inviare indietro un user.custom_tool_result. Vedi Session event stream per il flusso completo.

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"}
      }
    ]
  }
]'

# Consenti l'esecuzione dello strumento
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"
      }
    ]
  }'

# O rifiutalo con una spiegazione
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."
      }
    ]
  }'